Changes between Initial Version and Version 1 of XmlRpcTryUploadSubtitles

Timestamp:

Sep 27, 2008, 5:21:11 PM (16 years ago)

Author:

guest

Comment:

Created this page [Majky]

XmlRpcTryUploadSubtitles

@@ +1 @@
+
+[[PageOutline(3-4, Sections)]]
+
+== !TryUploadSubtitles == 
+
+=== Intro ===
+
+  try to upload subtitles, perform pre-upload checking (i.e. check if subtitles already exist on server)
+
+
+----
+=== Description ===
+
+  '''struct !TryUploadSubtitles(string $token, struct('cd1' => struct('subhash' => string $submd5hash, 'subfilename' => string $subfilename, 'moviehash' => string $moviehash, 'moviebytesize' => string double $moviesize, 'movietimems' => int $movietimems, 'movieframes' => int $movieframes, 'moviefps' => double $moviefps, 'moviefilename' => string $moviefilename) $subfile, 'cd2' => struct(...) $subfile) $subs)'''
+
+  This function is used to perform pre-upload checking on given subtitle files ''subfiles''. It will check if given subtitles are well-formed, if they already exist on the server, etc.
+
+  This must be called '''before''' [wiki:XmlRpcUploadSubtitles UploadSubtitles()].
+  
+  It takes 2 parameters, first is the session token, second is a structure of information for subtitles to be uploaded, minimum ''cd1'' (one subtitle file) is required.
+  
+  The function returns ''alreadyindb'' = 1 when subtitles already exist in the database.
+  
+  When they do not exist, [wiki:XmlRpcSearchSubtitles SearchSubtitles()] is called and API tries to find existing subtitles based on ''moviehash/moviebytesize''. If some results are found, information is returned in ''data'' key as [wiki:XmlRpcSearchSubtitles SearchSubtitles()] return structure.
+  This is good for uploading - user should have imdbid field already filled.
+
+
+----
+=== Parameters ===
+
+  Parameters structure:
+  {{{
+  struct(
+    (string) [token],
+    struct(
+      struct(
+        (string) [subhash],
+        (string) [subfilename],
+        (string) [moviehash],
+        (double) [moviebytesize],
+        (int)    [movietimems],
+        (int)    [movieframes],
+        (double) [moviefps],
+        (string) [moviefilename]
+      ) [cd1],
+      struct(
+        ... same structure as cd1 ...
+      ) [cd2],
+      ... more subtitle file structures go here (if any) ...
+    )
+  )
+  }}}
+
+  ''token (required)''::
+    token string identifying user's session, taken from [XmlRpcLogIn LogIn] output structure.
+  ''subs''::
+    structure of subtitle file information, contains one or more ''subfile'' structures
+    ''subfile''::
+      * structure containing information about one subtitle file
+      * mandatory fields are: ''subhash'', ''subfilename'', ''[wiki:HashSourceCodes moviehash]'', ''moviebytesize'', ''moviefilename''.
+      * ''subhash'': MD5 hash of subtitle file contents
+      * ''subfilename'': subtitle filename      
+      * 'moviehash'': hash calculated for the video file contents, see ''[wiki:HashSourceCodes Hash Source Codes]'' for various implementations
+      * ''moviebytesize': size of video file in bytes
+      * ''movietimems'': length of video in miliseconds
+      * ''movieframes': length of video in frames
+      * ''moviefps'': frame rate used in video file, e.g. 23.976
+      * ''moviefilename'': video filename                        
+
+
+----
+=== Return Values ===
+
+  Output is returned in this structure: 
+{{{
+  struct(
+    (string) [status],
+    (int)    [alreadyindb],
+    array(
+      struct(  <--- this is the usual subtitle file structure
+        (string) [IDMovieImdb],
+        (string) [MovieName],
+        (string) [MovieYear],
+        (string) [MovieHash],
+        (string) [MovieReleaseName],
+        (string) [IDMovie],
+        (string) [MovieNameEng]
+        (string) [MovieImdbRating],
+        
+        + 2 extra indicator fields:
+        (string) [MoviefilenameWasAlreadyInDb]
+        (string) [HashWasAlreadyInDb]
+        
+      ) [subfile]
+    ) [data]
+    (double) [seconds]
+  )
+}}}
+
+  and contains these elements:
+    ''status''::
+      function result code, see [XmlRpcStatusCode list of status codes]
+    ''alreadyindb''::
+      * indicator if subtitles are already available on the server.
+      * '''1''' if they are (upload should be interrupted, duplicate subtitle), 
+      * '''0''' if they're not (upload can continue)
+    ''data''::
+      * this array will contain one subtitle file structure (if found),
+      * this structure can be used to automatically gather information about movie,
+      * e.g. get IMDb ID so the user doesn't have to input it manually.
+    ''subfile''::
+      * informational subtitle file structure 
+      * see [wiki:XmlRpcStruSubFile subtitle file structure].
+      * ''!HashWasAlreadyInDb'' - 0 means new ''moviehash'' was inserted into the database.
+      * ''!MoviefilenameWasAlreadyInDb'' - 0 means new ''moviefilename'' was inserted into the database.
+    ''seconds''::
+      time taken to execute this command on server
+
+
+----
+=== Implementations ===
+
+  There are currently no available sample implementations.
+
+
+----
+=== Changelog ===
+
+  Version 1: created this function
+
+
+----
+=== Examples ===
+
+
+==== Input ====
+  
+{{{
+#!xml
+<methodCall>
+ <methodName>TryUploadSubtitles</methodName>
+ <params>
+  <param>
+   <value><string>d5pnounn3ea5aja0nn4inqamf2</string></value>
+  </param>
+  <param>
+   <value>
+    <struct>
+     <member>
+      <name>cd1</name>
+      <value>
+       <struct>
+        <member>
+         <name>subhash</name>
+         <value><string>ebe86f4a0357d8c1d635ec49f77e27d6</string></value>
+        </member>
+        <member>
+         <name>subfilename</name>
+         <value><string>almost.heros.1998.dvdrip.xvid.fragment.cze.srt</string></value>
+        </member>
+        <member>
+         <name>moviehash</name>
+         <value><string>89ceb12ab48e3b1f</string></value>
+        </member>
+        <member>
+         <name>moviebytesize</name>
+         <value><double>731508736</double></value>
+        </member>
+        <member>
+         <name>moviefps</name>
+         <value><double>23.976</double></value>
+        </member>
+        <member>
+         <name>movietimems</name>
+         <value><int>5413204</int></value>
+        </member>
+        <member>
+         <name>movieframes</name>
+         <value><int>129787</int></value>
+        </member>
+        <member>
+         <name>moviefilename</name>
+         <value><string>almost.heros.1998.dvdrip.xvid.fragment.avi</string></value>
+        </member>
+       </struct>
+      </value>
+     </member>
+     ... more subtitle files go here (if any, e.g. for cd2, etc.) ...
+    </struct>
+   </value>
+  </param>
+ </params>
+</methodCall>
+}}}
+
+  
+==== Output ====
+
+{{{
+#!xml
+<methodResponse>
+ <params>
+  <param>
+   <value>
+    <struct>
+     <member>
+      <name>status</name>
+      <value><string>200 OK</string></value>
+     </member>
+     <member>
+      <name>alreadyindb</name>
+      <value><int>0</int></value>
+     </member>
+     <member>
+      <name>data</name>
+      <value>
+       <array>
+        <data>
+         <value>
+          <struct>
+           <member>
+            <name>IDMovieImdb</name>
+            <value><string>119053</string></value>
+           </member>
+           <member>
+            <name>MovieName</name>
+            <value><string>Almost Heroes</string></value>
+           </member>
+           <member>
+            <name>MovieYear</name>
+            <value><string>1998</string></value>
+           </member>
+           <member>
+            <name>MovieHash</name>
+            <value><string>89ceb12ab48e3b1f</string></value>
+           </member>
+           <member>
+            <name>MovieReleaseName</name>
+            <value><string>Almost Heroes 1998 DVDRip XviD-FRAGMENT</string></value>
+           </member>
+           <member>
+            <name>IDMovie</name>
+            <value><string>13427</string></value>
+           </member>
+           <member>
+            <name>MovieNameEng</name>
+            <value><string>Almost History</string></value>
+           </member>
+           <member>
+            <name>MovieImdbRating</name>
+            <value><string>4.5</string></value>
+           </member>
+
+           ... the usual subtitle file structure continues, not important ...
+
+          </struct>
+         </value>
+        </data>
+       </array>
+      </value>
+     </member>
+     <member>
+      <name>seconds</name>
+      <value><double>0.065</double></value>
+     </member>
+    </struct>
+   </value>
+  </param>
+ </params>
+</methodResponse>
+}}}
+
+
+----
+=== Notes ===
+
+  none yet
+
+
+----
+=== See also ===
+
+  * [wiki:XmlRpcUploadSubtitles UploadSubtitles]
+
+
+----
+=== Comments ===
+
+        add your comments, hints and suggestions here if you like ...
+
+
+
+[Prev] [wiki:XmlRpcIntro Home] [wiki:XmlRpcUploadSubtitles Next]